Application programming interfaces (“APIs”) generally define functional or operation-based interfaces between systems or services and application programs that access the systems or services through the APIs. An API is often a collection of function declarations or a list of operations that specify what type of operations are provided by a system or service and how those operations are invoked from an application program.
There are many different types of APIs that provide interfaces to many different types of systems and services. The current document is directed to APIs for web services and other services provided by server computers, generally through the Internet, to remote client computers. One type of web-service API that has emerged as the prominent type of API for web services is referred to as a RESTful API. The acronym “REST” stands for “Representational State Transfer.” REST specifies a general style or architecture for client/server-based distributed computer systems. RESTful APIs are based on the hypertext transfer protocol (“HTTP”) and uniform resource identifiers (“URIs”). The HTTP protocol is an application-layer protocol for client/server-based exchange of information within distributed systems, and defines a small set of operations that allow client computers to request representations of various resources managed by a server, each identified by a unique URI, create new resources, update resources, and delete resources. Additional HTTP methods provide additional functionalities related to messages transmitted between clients and servers. The HTTP methods are referred to as “verbs,” meaning that they are the functions, operations, or methods of a RESTful API that represent actions. These verbs can be thought of as operating on resources, each identified by a unique URI, managed by a server. Often, the resources are hierarchically organized, with the hierarchical organization reflected in the structure of the URIs. A resource can be any type of entity that can be described by digitally encoded data.
The REST architecture is essentially an encapsulation of a set of best practices and general guidelines for developing service APIs. These are, in turn, encapsulated in a set of six constraints, which include: (1) a uniform-interface constraint; (2) a stateless constraint; (3) a cacheable constraint; (4) a client-server constraint; (5) a layered-system constraint; and (6) a code-on-demand constraint. The uniform-interface constraint defines the interface between clients and servers and decouples client functionality from server functionality. This provides many advantages in large distributed systems. When functionalities are distributed across clients and servers, rather than localized either in clients or servers, implementation becomes more difficult and complex, and requires many different types of distributed-computing techniques that add complexity and computational overhead to the distributed system. Another aspect of the uniform-interface constraint is that the restful APIs are largely resource-based. Clients request information about resources, which is returned to clients by servers as resource representations, and may also request certain operations on resources, such as updating the representations of resources maintained by the server. The uniform-interface constraint also provides that messages passed between clients and servers are self-descriptive. For example, each request message transmitted by a client to a server includes sufficient information to describe how the message is processed by the server. Message bodies may be encoded in JavaScript Object Notation (“JSON”) or extensible markup language (“XML”), both encoding systems for self-descriptive messages. Finally, the uniform-interface constraint specifies that links, essentially URIs, referred to as “hyperlinks,” are embedded by servers into message bodies to facilitate navigation by clients through the API and resource-representation acquisition, as well as for other purposes.
A RESTful API is stateless. In other words, servers do not save state information for particular client computers across multiple resource requests. Instead, in a RESTful API, each request message contains sufficient information for a server to handle the request. As a consequence of this stateless architecture, when some type of context is maintained across multiple requests, it is the client computer's responsibility to maintain the context. This greatly simplifies server implementation.
The cacheable constraint specifies that response messages identify themselves as being cacheable or not cacheable, to facilitate caching of responses by client computers and various types of intermediate computers. Cacheable responses can be stored by client computers and intermediate computers to avoid the need for multiple client/server transactions that all involve a server returning the same resource representation in a response message.
The client-server constraint provides for separation of client-computer and server-computer responsibilities, which facilitates client and server implementations. Client computers are not concerned with data storage with respect to a service provided by a server computer, which facilitates the design and portability of client-computer code, while servers are not concerned with user interfaces for displaying resources to users or user-state information, which is the responsibility of client computers. By separating server and client functionality, complex implementations in which functionality is distributed across users and servers are avoided, as are the many complexities and overheads associated with such distributed functionalities.
The layered-system constraint facilitates the scalability and ability for load balancing of server functionality. The server that provides a service via a RESTful API may be a single server or a hierarchically organized collection of end servers and intermediary servers but, in both cases, the service is accessed in identical fashion by client computers, which remain unaware of the server-side implementation.
The optional code-on-demand constraint facilitates the extension and/or customization of service functionality by allowing servers to transfer executables, such as Java applets and client-side JavaScript scripts, to client computers. This and other features of RESTful APIs allow for RESTful apps to be dynamically extended and modified, even after initial deployment.
While REST is, in part, based on the premise that RESTful APIs can be extended, over time, to provide new and additional types of functionalities, REST does not specify how the extension of APIs can be implemented, other than providing for the return of hyperlinks, by servers, in response-message bodies as well as the return of executable code by servers to client computers. While these features of REST form a basis for API extensibility, designers and developers of web services face significant challenges and hurdles in developing and deploying practical extensible services and APIs.